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Programming is a lot more than just writing algorithms or programs. Pro- 
gramming is all about communication. Communication with others: not only 
with the other programmers who will be involved in your development effort, 
but also with yourself. Indeed, finding good names is a really important task 
because using the right name often opens the door to new spaces where your 
design can bloom and expand. 


The purpose of a programming style guide such as this book is to provide a 
simple vehicle for addressing the needs of good communication. The goal is to 
make the source code clear, easy to read, and easy to understand and extend. 


These conventions are not cast in stone, but they set the foundation of a com- 
mon culture. Culture is important when programming. 


We were influenced by the excellent little book called Smalltalk with Style. We 
hope that you will enjoy this one and that it will help you become a better 
communicative designer. 


Feedback and suggestions are welcome at stephane.ducasse@inria.fr. 


Pull requests on https://github.com/SquareBracketAssociates/Booklet-PharoWithStyle 
are also welcome. 


Special thank to Réné-Paul Mages, Christopher Furhman, Benoit St Jean and 
Masashi Fujita, Nathan Reilly, Esteban Maringolo, Hernan Morales for their 
feedback. 


S. Ducasse - 12 February 2022. 


1.1 


1.2 


CHAPTER 


General naming conventions 


In this chapter, we will start with guidelines about names. 


Indeed, names are important. And using good names is the cornerstone of 
writing good software. This is true in any language. We will never repeat it 
enough. 


Now, finding a good name is sometimes difficult. To help, good names are of- 
ten driven by a domain or an ecosystem. Finally, the object-oriented program- 
ming paradigm gives some context that is useful: For example, the Don’t ask, 
tell” motto favors active and direct orders for method names. 


Guideline: Favor simple direct meaning 


Some native English speakers use more precise, but less common terms. Con- 
sider that your software may be read by people from different cultures. So use 
simple, mainstream, and common terms. Note that this does not mean that 
you should not use precise terms. Avoid hidden or implied meanings that can 
only be understood by a limited group of people. Make information explicit 
and clear. 


Guideline: Use descriptive names 


Choose descriptive names that capture domain entities unambiguously. Avoid 
cryptic names. Characters are cheap, so do not count them. If you are slow at 
typing then use the completion engine. 


1.3 


General naming conventions 


Prefer 
| dayOfWeek 


over 


| Not dow 


Prefer 


seconds 


over 


| Not sec 


Prefer 


| copyMenu 


over 


| Not cMenu 


Guideline: Pay attention to meaning 


Pharo uses English as main language. It looks strange to mention it, but this 
has some implications. We should pay attention to two mistakes that non na- 
tive english speakers tend to do: first, adjective inversion, and second, keeping 
the plural form during inversion of composition (using of). 


Adjective inversion 


Non-English native speakers often misplace word qualifiers (adjective). In En- 
glish, the qualifier is often before the word it qualifies. In Pharo, we follow 
such a convention. 


Prefer 


| DateParser 


over 


[Not ParserForDate 


or 


| Not ParserDate 


Prefer 


userAssociation 


1.4 


1.4 Guideline: Follow domain 


(an association of users) 


over 


[ Not associationUser 


No plural inside 


In English, the names of methods can also be written method names. Notice 
that in such a situation there is no s in method. 
Prefer 


| userAssociation 


over 


[ Not usersAssociation 


Avoid homographs 


Compare the three following variables: 


sizeToRead 
sizeJustRead 
readSize 


In this situation, avoid homographs (https://en.wiktionary.org/wiki/nomograph). 
That is, words that are written the same way but can have different meanings 
or pronunciations. For example, Did you read that book? ... Yes, I read it yesterday. 
About readSize: does this mean that the size was just read (red) or that it is 
the size to read (reed)? 


Favor words with a unique pronunciation. 


Guideline: Follow domain 


Follow the domain concepts and culture of the project. Do not invent your own 
terms because you think they are better. Favor regularity (consistency) over 
preciseness. 
Prefer 

[ GnatXmlNode 


over 


[not GNAT_XML_Object 


1.5 


1.6 


1.7 


General naming conventions 


When representing the XML Ada abstract syntax tree in Pharo, we should not 
follow Ada naming conventions. The name should convey that the class is an 
abstract syntax tree node. Hence, GnatXm1Node is much better than GnatXm- 
LObject. 


Another example is the following: In Moose, an importer is an object creating 
FAMIX entities (classes, methods, etc.) from the data structure representing a 
language element, usually an Abstract Syntax Tree (AST). Therefore GNATIn- 
staller, which creates entities from an AST, should be renamed Gnat Im- 
porter and GNATImporter, which loads an AST in memory should be renamed 
GnatASTLoader. 


Guideline: Favor unique meaning and pronunciation 


Choose names that have a unique meaning. Avoid homographs. 


Prefer 
sizeToRead 
sizeJustRead 
over 


[ Not readSize 


Does this mean that the size was just read (red) or is it the size to read (reed)? 


Guideline: Limit or use abbreviations consistently 


Abbreviations or acronisms are often obscure to newcomers. Now they are 
often handy so when you use them use consistently. 
Prefer 

[ ASTNode 


over 


TreeNode 
AbstractSyntaxTreeNode 


Guideline: Avoid numbers 


It can be handy when trying something new to reuse an identifier and add a 
number to it. Now limit this practice to your development session. Indeed, 
a number does not help the reader understand the difference. As a general 
principle, keeping multiple implementations of the same classes is a way to 


1.8 Conclusion 


propose rotten code. So if you want to keep several versions then make sure 
that why several versions are kept is made clear. 
Prefer 


StackBasedInlineParser 
NewInlineParser 
CleanerInlineParser 


over 


[ InlineParser2 


1.8 Conclusion 


The guidelines presented so far are general. We will see that we also have 
guidelines for classes and variables. 


2.1 


CHAPTER 2 a 


About class names 


In object-oriented programming, classes play an important role. They are fac- 
tories of objects, and as such, they are important for conveying the main ab- 
stractions within an application. 


Guideline: Use direct and natural style 


Often, classes represent objects, even abstract ones. Use the names that fit the 
best without inventing some clunky new terms. 


Prefer 


Terminal 


over 


| PlaceToDisplayInformation 


Some classes represent an action (such as Visitor) or process. 


| RBReadBeforeWrittenTester 
MicHTMLWriter 


Finally, some may represent a particular state. In Pharo, announcements fol- 
low the convention of finishing with the verb in the past tense. It contradicts 
English conventions, but it is applied uniformly. 


IcePackageLoaded 
MCVersionSaved 
RubBoundsChanged 


2.2 


2.3 


About class names 


Avoid class name using gerund 


RBParsing 
OpeningFile 


Guideline: Use natural language 


When defining class names, avoid abbreviations that are not obvious, avoid 
shortening names, and favor natural language. 


Prefer 


| RandomNumberGenerator 


over 


| RandNumbGen 


Prefer 


| CSVImporter 


over 


| CSVImport 


Prefer 


| RemoteControl 


over 


| RemControl 


Prefer 


| Player 


over 


| BoardMan 


Guideline: Do not expose implementation 


A class name should not expose the implementation the class uses. This is im- 
portant because implementation may change in the future. 


Prefer 


PropertyName 
ContactBook 


over 
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2.4 


2.5 


2.6 


2.4 Guideline: Avoid to use plural for class names 


PropertyNameString 
ContactDictionary 


Guideline: Avoid to use plural for class names 


A class often has many instances. TestCase classes are special classes where 
their methods are individual tests. Still, it is really awkward to have a class 
ending with S. 


Prefer 


[ AthensTextRenderManualTest 


over 


[ AthensTextRenderManualTests 


Of course some domain names ends with S, in such as case just follow the con- 
vention. 


Prefer 
[ NetworkSystemSettings 


Guideline: Avoid name collisions 


To avoid name space collisions, add a prefix indicative of the project to the 
name of the class. 


Prefer 


PRDocument 
CmdMessage 


Note You may find that Pharo is lacking a namespace. If you have a cou- 
ple hundred thousand euros, we can fix that! 


Note, however, that even with a namespace you will have to pay attention that 
your namespace name does not collide with another one. 


Guideline: Class names should indicate the class’ par- 
ent 


Suffix class names with the root class to convey the kind of object we are talk- 
ing about. 
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2.7 


About class names 


For example, without the Morph suffix, the reader is forced to check the super- 
class to understand if the class is about a graphical object or not. 


Prefer 


| ClyBrowserButtonMorph 


over 


| ClyBrowserButton 


Prefer 


[ ClyQueryViewMorph 


over 


[ ClyQueryView 


Prefer 


| SpLayoutHelpTopics 


over 


| SpLayouts 


In the following, not mentioning the Presenter suffix makes it unclear to the 
reader that it is a Presenter object as opposed to a Model object. 
Prefer 


| ApplicationWithToolBarPresenter 


over 


| ApplicationWithToolbar 


In the next example, DynamicWidgetChange does not convey that this is not 
a domain object representing a change, but a Presenter object in the Model- 
View-Presenter triad: 


| Dynami cWidgetChangePresenter 


over 


| Dynami cWidgetChange 


Conclusion 


Finding a good name is often difficult. However, nobody forces you to find it 
right upfront. And you can always change a name once you find a good one. 


A good way to find good names is to write unit tests. 
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2.7 Conclusion 


When you write unit tests, you are the first client of your code. You can then 
see if the names you chose let you write coherent and comprehensible little 
stories. You can explore the names you picked up and rename them. 
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3.1 


CHAPTER 3 o 


About identifier format 


While in the previous chapters we focused on identifiers or class variables, this 
chapter focuses on the form or format of such names. Indeed, writing software 
is about writing sentences that seamlessly integrate with existing ones. You 
do not want your program to be easily identifiable as an existing one. This is 
particularly true for multiple developer projects with common code owner- 
ship. Note that even if you are working on a single-person project, you will use 
existing class libraries and you do not want to have your ’ugly’ code stepping 
out. 


Guideline: Avoid underscores and favor camel case 


The form or format of identifiers is also important. Following the form pro- 
moted by a complete ecosystem will make your software more readable and 
acceptable by others. This is true in any programming language. 


Because Pharo and its ecosystem use camel case for class, variable, and method 
names. Avoid using underscores. 


Prefer 


| timeOfDay 


over 


| timeofday 
| time_of_day 


Prefer 


| GnatXmlNode 
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3.2 


3.3 


About identifier format 


over 
| GNAT_XML_Object 


Prefer 


| releasedx 


over 


[| released_X 


Prefer 
| | scaledX reducedX | 


over 


[| scaled_X reduced _X | 


When creating private low-level methods that bind to external C-libraries, you 
may want to use underscores to follow C conventions to ease tracing back the 
communication between libraries. In such a case, limit your use to carefully 
thought-out cases. 


Guideline: CamelCase fully identifiers 


Use consistently camel case on the full length of an identifier. 
Prefer 


| readyForNextItem 


over 


| readyFornextitem 


Guideline: Shared variables start with uppercase 
Begin class names, global variables, pool variables, and class variables with an 
uppercase letter. If the word is compound, then use camel case for the rest. 


Point "Class" 
Transcript "global variable" 
PackageGlobalOrganizer "class variables" 
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3.4 


3-5 


3.4 Guideline: Private variables start with lowercase 


Guideline: Private variables start with lowercase 


Begin instance variables, temporary variables, method parameters, and method 
selectors with lowercase. If the word is compound, then use camel case for the 
rest. 


| address 
classExtensionSelectors 
classTags 


Prefer 


| | dataset f xMatrix scale x | 


over 


| | dataset f Xmatrix scale X | 


Guideline: Convey language semantics 


Remember MaxLimit, maxLimit, maxlimit, and MAXLIMIT are all different 
identifiers in Pharo. 


| MaxLimit maxLimit | 
MaxLimit := 10. 
maxLimit := 20. 
MaxLimit 

>>> 10 


Still, Pharo favors the camel case, so use it systematically for words. Wikipedia 
defines camel case as: Camel case (stylized as camelCase) is the practice of 
writing phrases such that each word or abbreviation in the middle of the phrase 
begins with a capital letter, with no intervening spaces or punctuation. 


For local variables. 
Method parameters and instance variables, use 


| maxLimit 


instead of 


maxlimit 
MAXLIMIT 


For classes, or shared variables 


Use 
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3.6 


3-7 


About identifier format 


OrderedCollection 
MaxLimit 


instead of 


ORDEREDCOLLECTION 
MAXLIMIT 


Note In a compound word, do not confuse a prefix or suffix with a word 
when trying to determine which words should begin with an uppercase let- 
ter. For example, some readers may think that the ”c” in subclass should 
be uppercase, but sub is a prefix, not a word. When in doubt about prefixes 
and suffixes, check a dictionary. 


Prefer 


| superclass 


over 


| superClass 


Guideline: Method selectors start with lowercase 


Prefer 
| getMethodsNamesFromACLass: aClass 
| methodsNames | 
methodsNames := aClass selectors. 


methodsNames do: [ :each | names add: each ] 


over 


| GetMethodsNamesFromAClass: aClass 
| methodsNames | 
methodsNames := aClass selectors. 
methodsNames do: [ :each | names add: each ] 


Also, in this example, the method selector is not good because method names 
are called selectors in Pharo. In addition in English methodsNames should be 
written methodNames. It should be gatherSelectorsFrom: or something sim- 
ilar. 


Conclusion 


This is a bit obvious, but as a developer you should follow language conven- 
tions. 
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3.7 Conclusion 


This is not because Pharo is permissive that you should bend the rules. Doing 
so will only confuse you and other developers. So use camel case. Remember, 
private or local variables start with a lowercase letter, while class variables 
start with an uppercase letter. 
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4.1 


CHAPTER 


About variable names 


When choosing an appropriate name for a variable, the developer is faced with 
the decision: Should I choose a name that conveys semantic meaning to tell the user 
how to use the variable, or should I choose a name that indicates the type of object the 
variable is storing? There are good arguments for both styles. Let us see what 
the guidelines are that can help us find the right balance. 


Guideline: Favor semantic variables 


A semantic name is less restrictive than a type name. When modifying code, 
it is possible that a variable may change type. But unless one redefines the 
method, the semantics of it will not change. We recommend using semanti- 
cally meaningful names wherever possible. 


In the example below, the typed variable does not indicate how it will be used, 
whereas the semantic variable does. 
Prefer 


"Semantic variable" 
newSizeOfArray := numberOfAdults size max: numberOfChildren size 


over 


"Typed variable" 
anInteger := numberOfAdults size max: numberOfChildren size 


Note that semantic names can convey variable roles. Having more information 
is definitely useful for clients of the code. 
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4.2 


About variable names 


Prefer 


"Semantic variable" 
selectFrom: aBeginningDate to: anEndDate 


over 
"Type variable" 
selectFrom: aDate to: anotherDate 


Finding a semantic name is not always as obvious as demonstrated above. 
There are cases in which choosing a descriptive semantic name is difficult. 


Guideline: Use typed variables to indicate API 


Using a type variable is an interesting way to convey the API (set of messages) 
that the object held in the variable responds to. 


Below aDictionary conveys that the argument should have the same API as a 
Dictionary (at:, at:put:) 
Prefer 


| properties: aDictionary 


over 
| properties: map 
You may also want to stress specific types in an API reference to the interface 
that the object implements. 


Prefer 


[ properties: aPuttable 


over 


[ properties: aCollection 


Suppose a String, a Symbol, and nil are valid for a parameter. A developer may 
be tempted to use the name aStringOrSymbolOrNil. 


You may be tempted to aString or anObject. anObject is not really helping 
the developer who will have to use such variables. At the minimum, such a use 
should be accompanied by a comment that says, ”anObject can be a String or 
aSymbol” 


Some developers may argue that type variables should not refer to classes that 
do not exist. We disagree. As shown in the following guidelines, it is a lot bet- 
ter to indicate that an argument is a block expecting two arguments (hence a 
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4.3 


4.4 


4.3 Guideline: Get the best from semantic and type variable 


binary block) than to just mention a block. And this works even if there is no 
binary block class in the system. 


Prefer 


[ inject: anObject into: aBinaryBlock 


over 


[ inject: anObject into: aBlock 


Note that for inject:into: the best naming is to mix semantic and type nam- 
ing as in 


[ inject: initialValue into: aBinaryBlock 


Guideline: Get the best from semantic and type vari- 
able 


A good practice is to use a mixture of both semantic and typed variable names. 
Method parameter names are usually named after their type. Instances, classes, 
and temporary variables usually have a semantic name. In some cases, a com- 
bination of both can be given in the names. 


Prefer 


[ ifTrue: trueBlock ifFalse: falseBlock 


over 

ifTrue: block1 ifFalse: block2 

ifTrue: action1 ifFalse: action2 

The following are other examples of good names. 


inject: initialValue into: aBinaryBlock 
copyFrom: start to: stop 

findFirst: aBlock ifNone: errorBlock 
paddedTo: newLength with: anObject 


Guideline: Use semantics for state variable 
State variable names (instance variables, class variables, or class instance vari- 


ables) are usually semantic-based. A combination of semantic and type infor- 
mation can be really powerful, too. 


Prefer 
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4.5 


About variable names 


| "In class PhoneBook" 


phoneNumber 


name 


over 


number 


lLabelForPerson 


Guideline: Use predicate for Boolean 


Use predicate clauses or adjectives for Boolean objects or states. Do not use 
predicate clauses for non-Boolean states. 
Prefer 


alarmEnabled 
isAlarmEnabled 


over 


| alarm 


4.6 Guideline: Use common nouns and phrases 


Use common nouns and phrases for objects that are not Boolean. 


[ "In class Vehicle..." 
numberOfTires 
numberOfDoors 

"In class AlarmClock..." 

time 

alarmTime 


"In class TypeSetter... 
page 
font 
outputDevice 


Note that you can also use count instead of numberOf as in the following ex- 
ample: 


numberOfTires 
tireCount 
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CHAPTER 5 a 


About method names 


Method names in Pharo are called selectors. They are used in messages and 
are the main vehicle to convey adequate meaning to computation. From that 
perspective, it is really important to use them to convey the exact meaning 
of the computation they perform. The correct use of words and the design of 
selectors are then important. 


5.1 Guideline: Choose selectors to form short sentences 


Choose method names so that someone reading the message can read the ex- 
pression as if it were a sentence. 
Prefer 


| FileDescriptor seekTo: word from: self position 


over 


| FileDescriptor lseek: word at: self position 


Write the test first, and make sure that your test scenario reads well. 


5.2 Guideline: Use imperative verbs for actions 


Use imperative verbs for message which perform an action. 


transform 
selectors do: [:each | self pushDown: each]. 
selectors do: [:each | class removeMethod: each] 
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5:3 


About method names 


Prefer 


| aReadStream peek 


over 


| aReadStream word 


Prefer 

| aFace lookSurprised 
aFace beSurprised 
over 


aFace surprised 


| skipSeparators 


Pay attention to the fact that some words can be interpreted as interrogatives, 
whereas you want to give them an imperative meaning. 


For example, compare: 
| optimized 
and 


| triggerOptimization 


This is why using beOptimized would be better than a simple optimized and 
why isOptimized is better for the interrogative form. 


Guideline: Prefix selector with as for conversion 


When converting an object to another one, the convention is to prefix the class 
name of the target with as. 


| anArray asOrderedCollection 


Favor the use of existing classes. 


5.4 Guideline: Indicate flow with preposition 


When a process state is going from one object to another, indicate the direc- 
tion using meaningful names. 


For example, flattenProperties: is not a good name because it does not 
convey where the properties will be flattened. 


[ aConfiguration flattenProperties: aDictionary 
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5:5 


5.5 Guideline: Indicate returned type 


Better names such as flattenPropertiesFrom: and flattenPropertiesInto: 
are much better because there are no ambiguities. 


| aConfiguration flattenPropertiesFrom: aDictionary 
aConfiguration flattenPropertiesInto: aDictionary 


Here are more examples 


| changeField: anInteger to: anObject 


Prefer 


| ReadWriteStream on: aCollection. 


over 


| ReadWriteStream for: aCollection. 


Prefer 


[ File openOn: stream 


over 


| File with: stream 


Prefer 


[ display: anObject on: aMedium 


over 


[ display: anObject using: aMedium 


Guideline: Indicate returned type 


When a method returns an object (different from the receiver) and this object 
is not polymorphic with the receiver, it is important to mention it. Since Pharo 
is not statically typed, we can use the selector name to give such information 
to the sender of the message. 


For example, the method characterSeparatorMethodSignatureFor: ofthe 
pretty printer did not return a character but a block, as shown below: 


characterSeparatorMethodSignatureFor: aMethodNode 
Py 
(self needsMethodSignatureOnMultipleLinesFor: aMethodNode) 
ifTfrue: [ self newLine ] 
ifFalse: [ self space ] ] 


Favor characterSeparatorMethodSignatureBlockFor: over characterSep- 
aratorMethodSignatureFor: when the method returns block and not a char- 
acter as characterSeparatorMethodSignatureFor: indicates. 
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5.6 


5-7 


About method names 


A much better design is to rewrite this method and its users to use a character. 
Returning a block in such a situation is overkill. 


The following method is corresponding to its name. 


characterSeparatorMethodSignatureFor: aMethodNode 
^ (self needsMethodSignatureOnMultipleLinesFor: aMethodNode) 
ifTfrue: [ self newLine ] 
ifFalse: [ self space ] 


A good example is the API of the FileReference class. The message path- 
String indicates clearly that it returns the path as a string while to access the 
path object the message path should be used. 


Guideline: Use interrogative form for testing 


When interrogating the state of an object, use a selector beginning with a verb 
such as has, is, does,... 


Prefer 


| isAtLineEnd 


over 


| atLineEnd 


| aVehicle hasFourWheels 


over 


[ avehicle fourWheels 


Guideline: Avoid using parameter and variable name 
type 


Avoid the parameter type or name in the method name if you are using typed 
parameter names. 


Prefer 


| filesystem at: aKey put: aFile 


over 


| fileSystem atKey: aKey putFile: aFile 


| "for semantic-based parameter names" 
fileSystem atKey: index putFile: pathName 
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5.8 


5-9 


[ "useful when your class has several #at:put: methods 
fileSystem definitionAt: aKey put: definition 


5.8 Guideline: Use accessors or not 


Prefer 


aFace changeTo: expression 


over 


aFace changeExpressionTo: expression 


Guideline: Use accessors or not 


There are different schools about whether to use accessors. In his seminal 


book, Kent Beck discusses it in depth. Here we give a list of arguments for and 


against, and you should decide and follow the conventions of the project you 
work on. In any case, whether you use accessors or not, be consistent. 


Arguments in favor of accessors: 

e Accessors abstract from the exact state internal representation. 

e Accessors may hide that values are derived or not. 

e Subclasses may freely redefine the way accessors are implemented. 
Arguments against accessor use: 

e Accessors expose the internal state of an object. 


e When the class is small, using accessors may increase the number of 
methods. 


e Using refactorings, we can always easily introduce accessors. 


Guideline: Name accessors following variable name 


When you use accessors, name them consistently: 

* The getter is name as the variable it refers to. 

e The setter is the same but with an extra terminating colon :. 
For getter, prefer 
tiles 


^ tiles 


over 


getTiles 
^ tiles 


Do not use get or set in accessor selectors! 
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About method names 


Watch out 


Pay attention: a Setter is just setting a value and just returning (implicitly) the 
receiver. The following setter definition is not correct. 


| BinaryNode >> root: rootNode 
"Set a root node" 
^ root := rootNode 


Favor the following one instead: 


| BinaryNode >> root: rootNode 


root := rootNode 


Note that we do not need to comment a basic setter. 


For lazy initialization: 


tiles 
“tiles ifNil: [ tiles := OrderedCollection new ] 


For setters 


tiles: aCollection 
tiles := aCollection 


Put accessors in the 'accessing' protocols. When you have accessors doing 
extra work place them in a separate protocols to stress their difference. 


5.10 Guideline: Avoid return in lazy blocks 


You may want to use accessors to implement lazy initialization: the instance 
variable is initialized only if needed by checking if its value is nil. 


Do not place returns inside the block. 


Prefer 
| tiles 
“tiles ifNil: [ tiles := OrderedCollection new. 
over 
| tiles 
“tiles ifNil: [ tiles := OrderedCollection new. “tiles ] 
or even 
| tiles 


tiles ifNil: [ tiles := OrderedCollection new ]. 
^ tiles 
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5.11 Guideline: Avoid prefixing setters with set 


5.11 Guideline: Avoid prefixing setters with set 
Some developers may be tempted to name setter methods by prefixing the 
variable name 


Prefer 


tiles: aCollection 
tiles := aCollection 


over 


setTiles: aCollection 
tiles := aCollection 


Following K. Beck’s advice, use setTitles: only for private messages to ini- 
tialize objects from class side methods. 


5.12 Guideline: Use basic or raw to access low-level 


When two methods are needed for the same state variable, e.g., one returning 
the actual stored object and one returning and raising an event, prefix the one 
returning the actual object with the word basic or raw. 


method: aCompiledMethod 
self basicMethod: aCompiledMethod. 
self signal: MethodChanged 


basicMethod: aCompiledMethod 
method := aCompiledMethod 


When you have a getter that returns an object and a getter that returns a dif- 
ferent representation of the same object, add a suffix. 


path 
^ path 


pathString 
^ self path asString 


5.13 Guideline: Follow conventions and idioms 


When designing new objects, you may mimic some of the practices that the 
system already uses, for example, dictionaries, sets, etc. 
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5.14 


[series at: #k3 put: 


[series atKey: #k3 put: 


About method names 


Example 


Since a style sheet acts as a dictionary of properties, it is much better to use 
at: instead of get:, especially if you define the message to set a value to a 
property as at:put: and not set:. 


Prefer 


| stylesheet at: #fontColor 


over 


| stylesheet get: #fontColor 


Prefer 


[ aCollection groupedBy: [ :each | each odd ] 


over 


[ aCollection groupBy: [ :each | each odd ] 


Prefer 


xX. 
over 


X 


Prefer 


[ aCollection at: #toto 


over 


| aCollection atKey: #toto 


Guideline: Distinguish between class and instance se- 
lectors 


When defining a class method, we may name it the same way as an accessor 
of the class. Such practice hampers code readability in the sense that it is 
difficult to identify rapidly class methods. The senders will report both the 
instance and class usage. You may think that you will identify the message 
because the receiver is a class or an instance, but there are many situations 
where this is not the case. So it’s better to enrich the class method with a dis- 
tinct word. 
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5.14 Guideline: Distinguish between class and instance selectors 


Example 


In Pillar, a markup syntax to write documentation, annotations have param- 
eters and the accessor method parameters:. In some versions, an instance 
creation method with the same name as the accessor method exists. 


Reading the code of the parser and in particular the message parameters, it is 
not clear whether array second is a class or an instance. 


annotation 
^ super annotation 
==> 
[ :array | array second parameters: (array third ifNil: [ 
SmallDictionary new ]) ] 


To create an instance, it is better to name the method newParameter:. This 
way, we can immediately spot that the second element is a class. 


| annotation 
^ super annotation 
==> 
[ :array | array second newParameters: (array third ifNil: [ 
SmallDictionary new ]) ] 


| PRAbstractAnnotation class >> newParameters: aCollection 


| parameters | 
parameters := self checkKeysOf: aCollection. 
“ self new 
hadAllKeys: aCollection = parameters; 
parameters: parameters; 
yourself 


is better than 


| PRAbstractAnnotation class >> parameters: aCollection 
| parameters | 
parameters := self checkKeysOf: aCollection. 
“ self new 
hadAllKeys: aCollection = parameters; 
parameters: parameters; 
yourself 


Now, if you favor a fluid interface with many parameters, using withParame- 
ters: may not be good. 
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515 


About method names 


Guidelines: Follow existing protocols 


Protocols are ways to sort methods. It is important to place your methods into 
adequate protocols since it will ease future exploration of your class. 


Pharo provides auto categorisation of protocols for the common methods. So 
use it as much as possible. If you override your specific methods, place them in 
similar protocols. 
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6.1 


CHAPTER 6 a 


About code formatting 


Code formatting improves code comprehension. Readers are used to regular 
formatting. Don’t produce blobs of code. Copy the pros, follow the conven- 
tions. 


Guideline: Be consistent 


One important guideline when writing code is to follow conventions and, in 
addition, to be consistent. Systematically apply a formatting style. Keep the 
violations of conventions to a minimum. 


This applies at all levels: 
e Class names, 
* Method names, 
* Instance variable names, 
e Method body, and 
* Comments. 


Inconsistencies will break the reading flow and understanding of the code. 
Inconsistencies often indicate that different developers touched the code, and 
they may also be the source of bugs or indicate difficult places in the code. 
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About code formatting 


6.2 Guideline: Use the general method template 


* Separate method signature and comments from method body with an 
empty line. 


e Add an extra tab to the comments. 
e Add an extra line to stress the beginning of the method body. 
* Use a tab to separate the method body from the left margin. 


message selector and argument names 
"A comment following the guidelines." 


| temporary variables 
statements 


For example: 


| addLast: newObject 
"Add newObject to the end of the receiver. Answer newObject." 


lastIndex = array size ifTrue: [ self makeRoomAtLast ]. 
lLastIndex := lastIndex + 1. 

array at: lastIndex put: newObject. 

^ newObject 


Do not let space before the first word of the comment, align comment with 
method body, make sure that the reader can identify the beginning of the 
method body by placing an empty line between the method signature and the 
method body. 


Prefer the following 


| collectionNotIncluded 
"Return a collection for wich each element is not included in 
"nonEmpty'" 


A 


collectionWithoutNil 


over 


collectionNotIncluded 

return a collection for wich each element is not included in 
'nonEmpty' " 

collectionWithoutNil 


^ 


and over 
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6.3 


6.4 


6.3 Guideline: Indent method body 


collectionWithoutEqualElements 


return a collection not including equal elements 
“collectionWithoutEqualElements 


Guideline: Indent method body 


Use indentation to convey structure! Do not glue everything on the left mar- 
gin. 
Don’t indent your method like this: 

| initialize 

super initialize. 


symbols := Bag new. 
names := Set new 


Prefer 
| initialize 


super initialize. 
symbols := Bag new. 
names := Set new 


Guideline: Separate signature and comments from method 
body 


Separating method comments from the method implementation favor focus- 
ing our understanding to the right level. When we want to understand what 
the method does, we just have to read the comments. When we want to under- 
stand how the method is implemented, we just read the method body. 


Prefer 


| performCrawling: aName 
"Takes the last word in uppercase as a symbol and eventually add it 
to the bag symbols" 


name := aName copy. 

self getUpperCase. 

self stemSymbolFrom: aName. 
self toUpperCase. 


^ symbol 


over 
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6.5 


About code formatting 


Align comment with method body 


Use space to give breath to code 


addLast: newObject 
"Add newObject to the end of the receiver. Answer newObject." 


Highlight control flow lastIndex = array size — 
Qe ifTrue: [ self makeRoomAtLast ]. 


LlastIndex := LastIndex + 1. Separate signature and comments 
array at: LastIndex put: newObject. from method body 
^ newObject 


NN Indent method body 


Use tabs not spaces to indent 


Figure 6-14 A summary of good practices for code. 


| performCrawling: aName 

"Takes the last word in uppercase as a symbol and eventually add it 
to the bag symbols" 

name := aName copy. 

self getUpperCase. 

self stemSymbolFrom: aName. 

self toUpperCase. 

^ symbol 


Guideline: Use space to give breath to code 


Gluing all the characters together slows down reading. The reader needs to 
separate expressions. Gluing characters also hampers the identification of log- 
ical groups such as conditional branches. 


Put horizontal space to make it easier to read code and clearly identify vari- 
ables, arguments, assignments, block delimiters and returns. 


Prefer 


stemSymbolFrom: aName 


| stemmer symbol | 


stemmer := SymbolStemmer new. 
symbol := stemmer performCrawling: aName. 
^ symbol 

over 
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6.6 


6.7 


6.6 Guideline: Align properly 


stemSymbolFrom: aName 


[stemmer symbol] 
stemmer:=SymbolStemmer new. 
symbol:=stemmer performCrawling:aName. 
“symbol 


Parentheses do not need spaces (after ( and before )) since they show that an 
expression fits together. But favor space for [ and ], since they may contain 
complex expressions. 


drawOnAthensCanvas: aCanvas bounds: aRectangle color: aColor 


(self canDrawDecoratorsOn: aCanvas) ifFalse: [ ^ self ]. 
self drawOnAthensCanvas: aCanvas. 
next drawOnAthensCanvas: aCanvas bounds: aRectangle color: aColor 


Guideline: Align properly 
Understanding that a piece of code is a coherent expression eases understand- 
ing of more complex expressions. 


Make sure that your indentation reinforce the identification of block of func- 
tionality. 


Prefer 


| self phoneBook add: 


(Person new 
name: 'Robin'; 
city: 'Ottawa'; 
country: 'Canada'). 


over 


[ self phoneBook add: 


(Person new 

name: 'Robin'; 
city: ‘Ottawa'; 
country: 'Canada'). 


Guideline: Use tabs not spaces to indent and use spaces 
to help reading 


When navigating from one element to the next one, spaces and tabs are the 
same. Since they do not have a visual representation the reader cannot know 
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6.8 


About code formatting 


in advance if the white space in front of word is a tab or multiple spaces. It is 
then annoying to handle spaces manually. 


Avoid extra spaces at the beginning and use tabs to indent. 
Use one space to separate instructions. 
Avoid extra spaces everywhere: one is enough! 


Avoid extra spaces at the end of the line. 


Prefer 


Aa 


| stemSymbolFrom: aName 


| stemmer symbol | 


stemmer := SymbolStemmer new. 
symbol := stemmer performCrawling: aName. 
^ symbol 

over 


| stemSymbolFrom: aName 
[stemmer symbol] 


stemmer:=SymbolStemmer new. 


symbol:=stemmer performCrawling: aName. 
symbol 


Guideline: Do not break lines randomly 


White lines attract the eyes and force the reader to ask himself why the code 
is separated that way. Only separate method signature and comment from 
method body with a new line. 


Prefer 


l 
p 
[ 


over 
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p 
:= next. 


p isNotNil and: [ p isKindOf: RubParagraph ] ] 
whileFalse: [ p := p next ]. 


| paragraph 
"this method is here to find the paragraph in the chain, instead of 
relying on implementing #doesNotUnderstand: !!!" 


6.9 Guideline: Highlight control flow 


| paragraph 
"this method is here to find the paragraph in the chain, instead of 
relying on implementing #doesNotUnderstand: !!!" 


p := next. 


[ p isNotNil and: [ p isKindOf: RubParagraph ] ] whileFalse: [ 
p := p next. 
]. 


^ 


p 


6.9 Guideline: Highlight control flow 


Help the reader to understand control flow logic of your code by using inden- 
tation. 


Prefer 

[ size 

"Returns size of a tree - number of nodes in a tree" 
self root isNil 

iffrue: [ ^0 ]. 

self size: self root 


A 


over 

| size 

"Returns size of a tree - number of nodes in a tree" 
self root isNil 

iffrue: [ ^0 ]. 

“self size: self root. 


And prefer 


| depth: aNode 
"Returns depth of a tree starting from the given node" 
| leftDepth rightDepth | 
leftDepth := -1. 
aNode leftChild isNotNil 

ifTfrue: [ leftDepth := self depth: aNode leftChild ]. 
rightDepth := -1. 
aNode rightChild isNotNil 

ifTfrue: [ rightDepth := self depth: aNode rightChild ]. 
leftDepth > rightDepth 
iffrue: [ ^ 1 + leftDepth ] 


6.10 G 


About code formatting 


ifFalse: [^ 1 + rightDepth ]. 


over the terribly unreadable depth: aNode method. 


| depth: aNode 


"Returns depth of a tree starting from the given node" 
| leftDepth rightDepth | 

LeftDepth := -1. 

aNode leftChild isNotNil 

ifTfrue: [ leftDepth := self depth: aNode leftChild ]. 
rightDepth := -1. 

aNode rightChild isNotNil 

ifTfrue: [ rightDepth := self depth: aNode rightChild ]. 


( leftDepth > rightDepth ) 


iffrue: [ ^ (1 + leftDepth) ] 
ifFfalse: [^ (1 + rightDepth ) ]. 


uideline: Declare temporary close their use 


Temporary variables that will only be used within the block should not be de- 
fined outside of the block but in the local block. 


Prefer 


| | 
bl 


[1 
bl 
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block | 
ock := [ :arg | 
| local | 

. local... J 


over 


block local | 
ock := [: arg | 
. local... J 


7.1 


CHAPTER 


Comments 


Comments are important. Comments tell readers that they are smart guys and 
that they correctly guessed your intentions or your code. Do not believe those 

who claim that methods do not require comments. Obviously, this is what they 
mean: 


1. “Obvious methods” such as accessors do not need comments. 
2. A good comment does not describe how the code works in English. 


3. It is better to split long methods into smaller ones with a single responsi- 
bility, 


A 


. But a good comment is always welcome because it reinforces the under- 
standing of the reader. 


A comment should be adapted to the level of granularity (i.e., package, class, 
or method) to which it applies. 


Guideline: Method comments 


Method comments should contain sufficient information for a user to know 
exactly how to use the method, what the method does, including any side ef- 
fects, and what it answers without having to look at the source code. Imagine 
that the source code is not available. 


The main method comment is not about its implementation. Do not rephrase 
the implementation. The second level comments can include information 
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7.2 


Comments 


about the implementation. Insert a new line to separate the method comments 
from the method body. 


Collection >> asCommaString 
"Return collection printed as ‘a, b, c' 
"#('a' 'b' 'c') asCommaString >>> 'a, b, c'" 


Aa ' 


String streamContents: [:s | self asStringOn: s delimiter: ', '] 


The comments of a method should typically include: 


1. the method purpose (even if implemented or supplemented by a sub- 
class) 


2. the parameters and their types 

3. the possible return values and their types 

4. complex or tricky implementation details 

5. example usage, if applicable, as a separate comment 


Finally accessors do not need comments; the only comment that accessor 
could have is the purpose of the instance variable. 
day 


"Answer number of days (an instance of Integer) from 
the receiver to January 1, 1901." 


A 


day 


Guideline: Good comment do not paraphrase code 


Good Pharo source code is self-documenting, often making comments on state- 
ments redundant. Statements need only be commented upon to draw the 
reader’s attention. If the source code implements an algorithm that requires 

an explanation, then the steps of the algorithm should be commented as needed. 


Do not comment on an obvious fact that is expressed simply as plain code. 


Prefer 


| result | 
result := self employees 
collect: [:employee | employee salary > amount]. 


over 
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7:4 


7.3 Guideline: Use active voice and short sentences 


| result | 
"Store the employees who have a salary greater than in result." 
result := self employees 

collect: [:employee | employee salary > amount]. 


Guideline: Use active voice and short sentences 


When writing comments, use active voice and avoid long, convoluted sen- 
tences. A method comment should state what the method does, its arguments, 
its effects, and its output. 


Prefer 


| "Active voice" 
createShell 
"Create the receiver's shell. Hook the focus callback." 


over 


| "Passive voice" 
createShell 
"The receiver's shell is created. The focus callback is hooked." 


Guideline: Include executable comments 


Pharo offers executable examples in a comment using the message >>>. Exe- 
cutable examples in comments are super cool because, as the reader, you can 
execute the code and understand the parameters. In addition, the documen- 
tation is always synchronized because tools such as the test runner can check 
that examples are correct. 


| ProtoObject >> ifNil: nilBlock ifNotNil: ifNotNilBlock 

"If the receiver is not nil, pass it as argument to the 
ifNotNilBlock block 

else execute the nilBlock block " 

"(nil ifNil: [42] ifNotNil: [:o | 0 + 3 ] ) >>> 42" 

"(3 ifNil: [42] ifNotNil: [:o | o+ 3 ]) >>> 6" 


^ ifNotNilBlock cull: self 


| Object >> split: aSequenceableCollection 

"Split the argument using the receiver as a separator." 
"optimized version for single delimiters" 

"($/ split: '/foo/bar')>>>#('' 'foo' 'bar') asOrderedCollection" 
"([:cl c isSeparator] split: ‘aa bb cc dd') >>> #('aa' 'bb' 'cc 


'dd') asOrderedCollection" 
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Comments 


| result | 
result := OrderedCollection new: (aSequenceableCollection size / 2) 
asInteger. 


self split: aSequenceableCollection do: [ :item | 
result add: item ]. 
result 


Aa 


7.5 Guideline: Use CRC-driven class comments 


A class is not in isolation, but implements responsibilities (mainly one) and col- 
laborates with other entities. Therefore a class comment should be composed 
of at least 3 parts: the class, its responsibilities and how it uses its collabora- 
tors. The Class Responsibility Collaboration (CRC) pattern is powerful to design 
but also to comment classes. Use it for commenting class. 


Knowing the instance variables is the least important! 
Follow the template given by Pharo that is shown below. 


| Please comment me using the following template inspired by Class 
Responsibility Collaborator (CRC) design: 


For the Class part: 
State a one line summary. For example, "I represent a paragraph of 
text". 


For the Responsibility part: 
Three sentences about my main responsibilities - what I do, what I 
know. 


For the Collaborators Part: 
State my main collaborators and one line about how I interact with 
them. 


Public API and Key Messages 
- message one 
- message two 
- (for bonus points) how to create instances. 


One simple example is simply gorgeous. 


Internal Representation and Key Implementation Points. 


Implementation Points 
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7.6 


7.6 Guideline: Comment the unusual 


Guideline: Comment the unusual 


When a behavior is unusual, performing unexpected actions or using an unex- 
pected algorithm, it is important to comment on it. 


In general, comments should make irregular and unusual aspects clearer. You 
may want to include implementation-dependent or platform specific idiosyn- 
crasies. 
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8.2 


CHAPTER 


Powerful coding idioms 


Some coding idioms will make your code a lot clearer. Knowing them is also 
good because you will code faster. 


Guideline: Do not query twice for the same object 


The message ifNotNil: expects a block with one argument. This argument is 
the object that is not nil. 


For example, 


| self doAndReturnThat ifNotNil: [ :that | self doSomethingwith: that ] 


is better than: 


| | that | 


that := self doAndReturnThat. 


| that ifNotNil: [self doSomethingWith: that] 


Similarly have a look at the messages containing the ifPresent: variations. 


[aCol at: key ifPresent: [ :present | self doSomethingWith: present] 


Guideline: Move return outside branches 


When two branches of a condition are returning a value, better move the re- 
turn out of the blocks. 


When two branches of a condition are returning a value, better move the re- 
turn out of the blocks. 
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8.3 


8.4 


Powerful coding idioms 


Prefer 


| depth: aNode 
"Returns depth of a tree starting from the given node" 


^ leftDepth > rightDepth 
ifTfrue: [ 1 + leftDepth ] 
ifFalse: [ 1 + rightDepth ] 


over 


| depth: aNode 
"Returns depth of a tree starting from the given node" 


leftDepth > rightDepth 
iffrue: [ ^ 1 + leftDepth ] 


ifFfalse: [ ^ 1 + rightDepth ] 


Guideline: Use streamContents 


When you want to manipulate a potentially long stream you can avoid to have 
to define the explicit stream creation and access using streamContents with a 
block whose argument is a ready to use stream. 

Prefer 


[ String streamContents: [:s | self displayStringOn: s] 


over 


stream := WriteStream on: (String new: 1000). 
stream... 
^ stream contents 


Guideline: Preallocate overly large collections 


You may work on really large collections, and in such a case, the allocation of 
the collection can have a speed penalty. 


If you know in advance how large your collection will be, preallocate a big one 
and store elements in it: 


| list | 
list := OrderedCollection new: 10000. 
1 to: 10000 do: [ :i | 

list add: i ] 


You can use the method bench to get a first idea. 
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8.5 


8.5 Guideline: Use super to send a message with the same selector 


[El list | 


list := OrderedCollection new: 100000. 
1 to: 100000 do: [ :i | 

list add: i] ] bench 
"for 100,000 get 165.901 per second" 
"for 10,000 get 5484.903 per second" 


[| list | 
list := OrderedCollection new. 
1 to: 100000 do: [ :i | 
list add: i ] ] bench 
"for 100,000 get 79.368 per second" 


"for 10,000 get 5278.544 per second" 


Guideline: Use super to send a message with the same 
selector 


super is used to start the method lookup in the superclass of the class of the 
method containing super. However, super is only necessary when the method 
you want to invoke has the same than the current one since using self in such 
a case simply creates and infinite loop. 


For example, the following just creates an infinite loop, since the method ini- 
tialize is calling itself infinitively. 


initialize 


self initialize. 
self continue 


This is the only case where you must use super to invoke a method that can- 
not be reached by the method lookup when it starts from the class defining the 
method. The correct definition is then: 


initialize 


super initialize. 
self continue 


Now there is no need to use super for messages that have a different selector 
than the method they belong to. For example, there is no need to use super 
bar in the following, since the defining method is called foo and you send the 
message bar. 


foo 
super bar. 
self continue 
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Powerful coding idioms 


The correct definition is just to use self. 


foo 
self bar. 
self continue 


While using super often does not break your code, it may because if you have 
a method named bar in the same class this method will not be invoked. Always 
be cautious when reading or writing such code. 
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9.1 


CHAPTER 


Object initialization 


One key responsibility for a class is to correctly initialize the instance it cre- 
ates. This avoids placing the burden on clients of such objects. In this chapter, 
we will present some patterns to initialize objects. 


Guideline: Take advantage of automatic object initial- 
ization 

By default Pharo offers a way to initialize your objects. The method initial- 
ize is automatically sent by the method new. 


Imagine that we implement a game and that this game needs to initialize the 
number of turns it plays. Avoid forcing the clients of the game to have the re- 
sponsibility of initializing the turn. Indeed, if the clients forget to send the 
expression turn:, the game logic may be simply broken. 


| Game new turn: 0 


Therefore, when you want to initialize the state of your object, simply redefine 


Game >> initialize 
super initialize. 
turn := 0. 


This way Game new will automatically set the value for turn. 


From a test perspective, it is often a good practice to have a test covering the 
default initialization. 
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9.2 


9.3 


Object initialization 


GameTest >> testDefaultInitialization 


self assert: Game new turn equals: 0 


Guideline: No automatic initialize 


When you do not want to get the automatic initialization to happen you should 
use the message basicNew on the class side and create your own initialize- 
Something: method. 


Let us imagine that the computation of the tiles of a game would be costly or 
that there would be no simple default. We can propose a class creation inter- 
face whose responsibility is to request the mandatory information and initial- 
ize only what is needed for the object creation. 


Here we define a class method tileNumber :, and we do not invoke new but 
basicNew. Indeed new sends the message initialize and we do not want to 
pay the price for it. basicNew just allocates the new object and does not per- 
form any other operations. 
Game class >> tileNumber: aNumber 
“ self basicNew 
initializeTiles: aNumber ; 
yourself 


Now on the instance side we can define the initialization of tiles as shown by 
the method initializeTiles:. 


Game >> initializeTiles: aNumber 
tiles := Array new: aNumber 


If you use new instead of basicNew in previous definition, the initialize 
method and the method initializeTiles: will be executed. 


Guideline: No double super new initialize 


Since Pharo is automatically sending the message initialize as part of the 
object creation process using the pattern below, there is no need for the devel- 
oper to do it in addition. 


Now you may wonder what the problem is if you inadvertently redefine new in 
one of your classes as follows: 


Game class >> new 
^ super new initialize 


In Pharo, the method initialize of the class Game will be invoked twice. 
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9.4 Guideline: initialize does not need to return super 


9.4 Guideline: initialize does not need to return super 


The method initialize is a method that modifies the receiver. It is used by 
convention to initialize the default value of the receiver. It is invoked by de- 
fault by the message new 


The following definition is not idiomatic: 
initialize 
default := 'no'. 
“ super initialize 
First it returns a value and this value is not really used. Prefer the following 
definition: 
initialize 
default := 'no'. 


super initialize 


Second, the ordering implies that the first local information should be com- 
puted, then one of the superclasses. It may happen that you need this order, 
but it is rare, so prefer the following canonical form: 


initialize 


super initialize 
default := 'no'. 
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10.1 


CHAPTER 0 


Potential traps: A syntactic 
perspective 


Understanding possible mistakes is a nice way to avoid them or to spot errors 
made in your code. Here are some common mistakes. 


Guideline: Use parentheses to disambiguate messages 
with the same priority 


For keyword-messages 


The Pharo compiler does not know where to cut an expression composed on 
multiple keyword-based messages. For example, assert:includes: in the ex- 
pression self assert: uUMLClass variables includes: 'name' canbe 

a message that the object self can understand. For example testcases under- 
stand the message assert: equals: and the following expression is fully valid: 
self assert: uUMLClass variables equals: ‘name’. 


Therefore, this is the programmer responsibility to use parenthese to sepa- 
rate correctly the messages having the same priority. The following example 
illustrates this point. 


testDefineASimpleClass 
| uUMLClass | 


uUMLClass := UMLClass named: 'ComixSerie'. 
uUMLClass instVar: 'name'. 
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10.2 


Potential traps: A syntactic perspective 


i self assert: uUMLClass variables includes: 'name' 


There is no message assert:includes:. The expression uUMLClass vari- 
ables includes: 'name' should be parenthesized, because this is the result 
of the execution of this expression that should be passed as argument of the 
message assert:. 


testDefineASimpleClass 


| uUMLClass | 

uUMLClass := UMLClass named: 'ComixSerie'. 
uUMLClass instVar: 'name'. 

self assert: (uUMLClass variables includes: 'name') 


Between binary messages 


Pharo does not make any assumption about the possible mathematical mean- 
ing of messages. As a programmer you cannot describe the weight of a binary 
messages. It means that in an expression composed of multiple binary mes- 
sages, they will be executed from left to right. 


For example 1 + 2 * 3 returns 9 since first the message plus is resolved and 
its result is the receiver of the message +. 


poe 


>>> 9 


To get the correct mathematical behavior, one should use parentheses. 


Ee ae 


>>> 7 


Guideline: no need for extra parentheses 


There is no need for parentheses surrounding unary message. There is not 
much benefit to add parentheses around unaray messages. In Pharo unary 
messages are the messages that have the highest priority. They are executed 
first. 


Prefer 

[ xMatrix := PMMatrix rows: x asArrayOfRows. 
over 

[ xMatrix := PMMatrix rows: ( x asArrayOfRows ). 
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10.2 Guideline: no need for extra parentheses 


No parentheses around message with higher priority 


In the similar way, there is no need to put parentheses around binary mes- 
sages involved in keyword-based expressions. Binary messages are executed 
prior to keyword-messages. In the following = is executed before ifTrue:. 


Prefer 


| reducedX do: [ :row | 
(row at: 'target') = 'Iris-setosa' 
ifTfrue: [ a add: row asArray ] ]. 


over 

| reducedX do: [ :row | 

( (row at: 'target') = 'Iris-setosa') 
iffrue: [ a add: (row asArray) ] ]. 


Prefer 


| depth: aNode 
"Returns depth of a tree starting from the given node" 


| leftDepth rightDepth | 
leftDepth := -1. 
aNode lLeftChild isNotNil 

ifTfrue: [ leftDepth := self depth: aNode leftChild ]. 
rightDepth := -1. 
aNode rightChild isNotNil 

ifTfrue: [ rightDepth := self depth: aNode rightChild ]. 
^ leftDepth > rightDepth 

iffrue: [ 1 + leftDepth ] 

ifFalse: [ 1 + rightDepth ] 


over 


| depth: aNode 

"Returns depth of a tree starting from the given node" 

| leftDepth rightDepth | 

leftDepth := -1. 

aNode lLeftChild isNotNil 

iffrue: [ leftDepth := self depth: (aNode leftChild) ]. 
rightDepth := -1. 

aNode rightChild isNotNil 

iffrue: [ rightDepth := self depth: (aNode rightChild) ]. 


( leftDepth > rightDepth ) 
iffrue: [ ^ (1 + leftDepth) ] 
iffalse: [^ (1 + rightDepth ) ]. 
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10.3 


Potential traps: A syntactic perspective 


No parentheses around variable 


Putting parentheses around a variable does not produce an array, it has no ef- 
fect. Do not confuse parentheses and curly braces. Curly braces is a shortcut to 
produce an array with the elements they surround: { a } produces an array 
with one element whose value is the value held by the variable a as shown by 
the examples below. 


In this code snippet, {} creates an array. 


la | 

a := 12. 

{a} printString 
>>> #(12) 


In this snippet, the parentheses do not do anything. 


lal 

a := 12. 

(a) printString 
>>> 12 


No parentheses around single message 


There is no need to put extra parentheses over a single message. It has no ef- 
fect. Parentheses make sense to disambiguate one message over a set of mes- 
sages composing an expression. 


Prefer 

[m := pca transform: xMatrix 
over 

[m := (pca transform: xMatrix) 


Guideline: receiver of ifTrue:ifFalse: is a boolean 


Do not use a block as receiver ofa ifTrue:, ifFalse:, iffrue:ifFalse: or 
ifFalse:ifTrue: messages. 


The following expression is the following: 


lastNode = 0 
ifTrue:[ lastNode := curNode ] 
ifFalse:[ lastNode next: curNode ] 


The following expressions do not work 
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10.4 


10.5 


10.4 Guideline: receiver of whileTrue: is a block 


| [lastNode =0] value 
ifTrue:[ lastNode := curNode ] 
ifFalse:[ lastNode next: curNode ] 


| [lastNode =0] 
ifTrue:[ lastNode := curNode ] 
ifFalse:[ lastNode next: curNode ] 


Guideline: receiver of whileTrue: is a block 


The receiver of the message whileTrue: is a block, and its argument is, too. 
The following line is incorrect: 
[ (number < limit) whileTrue: [ do something ] 


The following line is correct: 


[ number < limit ] whileTrue: [ do something ] 


Guideline: Use a Block when you do not know execu- 
tion time 
Often newcomers get confused about when to use ( ) and[ ]. A good way to 
understand is that we should use [ ] when we do know whether an expression 
will be executed (may be multiple times). 
ifTrue:ifFalse: 
The conditional is always executed, while each of the arguments is a block be- 
cause we do not know which ones will be executed. 
lastNode = 0 
ifTrue: [ lastNode := curNode ] 
ifFalse: [ lastNode next: curNode ] 
timesRepeat: 
timesRepeat :’s argument is a block because we do not know how many times 
it will be executed. 
[n timesRepeat: [ lastNode := curNode next ] 
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Potential traps: A syntactic perspective 


do:/collect: 
The argument of iterators such as do:, collect :,... is a block because we do 
not know how many times (if any) the block will be executed. 


[ aCol do: [ :node | ...] 


10.6 Guideline: Avoid , when in loop 


In Pharo string concatenations are expressed using the message #,. 


'Pharo' , ' with Style' 
>>> 'Pharo with Style' 


The implementation of the method is however not really efficient since it 
copies the underlying collection during each concatenation as we show below. 
The alternative is to use a write stream or to use streamContents: but using a 
stream makes the code more complex. Therefore there is a key question to be 
answered: When is it pointless to use a WriteStream and just use #, ? 


Avoid #, when the code is in a loop or recursion, use a stream. 
[ String streamContents: [:s | 1 to: 10000 do: [ :i | s << i asString ]] 


Use #, when constructing error messages, class initialisation code, or situa- 
tions where there is no loop. 


Note that in printOn: methods, the argument is already a stream so we use it 
and avoid using message #,. 


Difference in speed 


The following snippets shows the difference in execution on large concatena- 
tions. 


fi String streamContents: [:s | 1 to: 10000 do: [ :i | s << i asString 


]] J] bench 
>>> '551.890 per second' 


1 to: 10000 do: [ :i | s := s, i asString ] ] bench 
>>> '8.465 per second' 


| [ String streamContents: [:s | 1 to: 1000 do: [ :i | s << i asString 
]] J bench 
>>> '6313.137 per second' 
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10.7 


10.8 


10.7 Guideline: super is just self 


[ls | 
Sus 
1 to: 1000 do: [ :i | s := s, i asString ] ] bench 
>>> '967.819 per second' 


Guideline: super is just self 


super is the receiver of the message, just as self. No super is not the super- 
class, nor an instance of the superclass. super is the receiver of the message. 


There is no need to use super when returning an expression not passing it as 
argument. For example passing super as argument is useless and show that 
the developer did fully get what super it. 


| foo 


anotherObject bar: super. 
self continue. 


Better use self 


| foo 


anotherObject bar: self. 
self continue. 


Similarly 


| foo 


^ super 


Better use self 


| foo 


^ self 


Guideline: Do not reuse temporaries 


Readable code is key and reusing a local temporary variable to store different 
objects during the execution of a method should be avoided. Creating a sep- 
arate temporary does not incur any execution cost. Therefore, create a tem- 
porary variable instead of storing different objects inside the same variable at 
different execution points of a method. 
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10.9 


10.10 


10.11 


10.12 


Potential traps: A syntactic perspective 


Guideline: Do not change behavior of well-known mes- 
sages 


When reading code, developers read it in the context of core libraries, a com- 
mon vocabulary, and expected behavior. Therefore, it is important not to de- 
fine methods having the same name as a common message but that exhibit 
different behaviors. 


When you define a method, you can check really fast using implementors if 
existing libraries have already defined such a message. 


Guideline: Use iterators 


Pharo has a large collection of really powerful iterators in its deep core. Use 
do:, collect:,select:, reject: to start with. 
Prefer 


[ collection do: [ :element | ... ] 


over 


[1 to: collection size do: [ :index | ... ] 


This is the only case where you must use super to invoke the method that can- 
not be reach by the method lookup when it starts from the class defining the 
method. The correct definition is then: 


Guideline: Avoid low-level messages 


Pharo offers a large set of low-level messages such as isKindOf:, isMem- 
berOf:, become:, canUnderstand:, doesNotUnderstand;:, .... Such messages 
are handy for constructing tools and the infrastructure of the language. How- 
ever, such methods make the code more complex and often more fragile. In 
addition, some are more costly and, in addition, break basic cross-references. 
So, always consider whether such methods are truly necessary. 


Guideline: Do not abuse blocks 


Blocks are powerful. They are handy because they are like anonymous meth- 
ods created on the fly. Avoid nest blocks and complex flow when explicit meth- 
ods are possible. 


Prefer 
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10.14 


10.13 Guideline: Do not write lengthly blocks 


| action1 


. code1 


action2 
. code2 


some method 
x <y 
ifTfrue: [ self action1 ] 
ifFasel: [ self action2 ] 


over 
[action1 := [ . codel ]. 
action2 := [ ... code2 ] 


some method 
x <y 
ifTrue: [ action1 value ] 
ifFasel: [ action2 value ] 


Guideline: Do not write lengthly blocks 


Now, writing long blocks is a problem because blocks are not methods and you 
cannot simply call them. In addition, blocks do not create simple hook meth- 
ods that subclasses can customize. 


A good practice is to keep the block body length short and to convert long 
blocks into methods and call such methods from the block. 


Prefer 


| messageWithBlock 


body of a long block 


| anObject use: [ self messageWithBlock ] 


over 


| anObject use: [ ... body of a long block ... ] 


Guideline: Exception catch MUST not be empty 


Exceptional behavior can be captured and controlled using on: do:. Now this 

is important not to catch an exceptional behavior and do nothing. This is ba- 
sically the worst thing you can do, and it will backfire on you months later. In 
addition, it makes your code super difficult to debug. 
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Potential traps: A syntactic perspective 


Prefer 


[ expression ] on: Error do: [:ex | Stdio stderr nextPutAll: ‘Error 
in...' ] 


over 


[E expression ] on: Error do: [] 


66 


CHAPTER 


Potential traps: About printing 
and Streams 


Stream usage in the case of printing objects may be sometimes confusing. In 
this chapter we clarify some of pitfalls. 


Guideline: printString vs. displayString 
Newcomers are often confused between printString and displayString and 
their counterparts printOn: and displayStringOn: :. 


* printString is used for debugging, that’s why the default implementa- 
tion shows the class name. It’s implemented by specializing printOn: 
on your classes. 


e displayString is used for nicely display objects in list. It is implemented 
by specializing displayStringOn: on your classes. 


If you have aPerson: 


aPerson printString 
>>> 'aPerson ('John Doe')' 


aPerson displayString 
>>> 'John Doe’ 
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11.2 


Potential traps: About printing and Streams 


Guideline: About printString 


Let us take a moment to step back about stream usage in printOn: methods. 
The printString method creates a stream and passes this stream as argu- 
ment of the printOn: method as shown below: 


[Object >> printString 


"Answer a String whose characters are a description of the receiver. 
If you want to print without a character limit, use fullPrintString. 


^ 


self printStringLimitedTo: 50000 


| Object >> printStringLimitedTo: limit 


"Answer a String whose characters are a description of the receiver. 
If you want to print without a character limit, use fullPrintString. 


“self printStringLimitedTo: limit using: [:s | self printOn: s] 


[Object >> printStringLimitedTo: limit using: printBlock 


"Answer a String whose characters are a description of the receiver 
produced by given printBlock. It ensures the result will be not 
bigger than given Limit" 


| limitedString | 

LimitedString := String streamContents: printBlock lLimitedTo: limit. 
LimitedString size < limit ifTrue: [^ limitedString]. 

^ limitedString , '...etc...' 


What you should see is that the method printStringLimitedTo:using: is 
creating a stream and passing it around. 


When you redefine the method printOn: in your class, if you send the mes- 
sage printString on the instance variables of your object, you are in fact cre- 
ating yet another stream and copying its contents in the first one. 


Here is an example: 


MessageTally >> displayStringOn: aStream 
self displayIdentifierOn: aStream. 
aStream 

nextPutAll: ' ('; 
nextPutALl: self tally printString; 
nextPutAll: ')' 


This is clearly counterproductive. It is much better to send the message print: 
to the stream or printOn: to the instance variable it as follows: 
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11.3 


11.3. Guideline: Unnecessary stream creation 


| MessageTally >> displayStringOn: aStream 
self displayIdentifierOn: aStream. 
aStream 
nextPutAll: ' ('; 
print: self tally; 
nextPutAll: ')' 


To understand what the method print:, here its definition: 


| Stream >> print: anObject 
"Have anObject print itself on the receiver." 


anObject printOn: self 


Pay attention, sending the printString message is often wrong and it is the 
duties of the system to do it. 


Guideline: Unnecessary stream creation 


Unnecessary stream creation can happen in other situations than printString. 
Here is an example taken from Pharo. 


| printProtocol: protocol sourceCode: sourceCode 


^ String streamContents: [ :stream | 
stream 
nextPutALl: '‘"protocol: '; 
nextPutALl: protocol printString; 
nextPut: $"; cr; cr; 
nextPutALl: sourceCode ] 


What you should see is that a stream is created and then another stream is 
created and discarded with the expression protocol printString. A better 
implementation is the following using print:. 


| printProtocol: protocol sourceCode: sourceCode 


^ String streamContents: [ :stream | 
stream 
nextPutALl: '‘"protocol: '; 
print: protocol; 
nextPut: $"; cr; cr; 
nextPutALl: sourceCode ] 
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Potential traps: About printing and Streams 


11.4 Guideline: printString vs. asString 
Another difficulty you may encounter is to see the difference between printString 
and asString. 


* printString is used for debugging, that’s why the default implementa- 
tion shows the class name. It’s implemented by specializing printon: 
on your classes. 


e asString converts an object into a string. It is equivalent to the toString( ) 
in other languages. 


Let us take an example with the symbol #foo. 
Printing the symbol #f 00 is just printing it as symbol. 


#foo printString 
>>> '#foo' 


Sending the message asString to the symbol #foo converts it to a string. 


#foo asString 
>>> 'foo' 


The situation is the same for strings but it can be a bit more destabilizing. The 
conversion of a string to a string is the string itself. 


'foo' asString 
>>> 'foo' 


Now printing a string includes the quotes and quotes should be double quoted. 


‘foo' printString 
>>> '''foo''' 
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12.1 


12.2 


CHAPTER 2 


Use Patterns 


In this chapter we present some points about existing libraries or functionality 
that are often misunderstood and lead to code of lesser quality. 


Guideline: Write small methods 


Long methods are a sign of less mature code. Indeed, small methods offer 
many strong advantages: 


Are easier to read and understand, 


Are easier to test, 


Are easier to reuse and compose, 


Are elementary pieces of customization. Indeed, sending a message to 
self creates a hook that subclasses can customize within their context. 
This is the foundation of object-oriented programming. 


As measured by Zaitsev and Ducasse, Pharo methods (excluding test methods) 
have 3 lines of code as a median value. Therefore, this is not just anecdotal but 
an important point. 


Guideline: Avoid singletons 
Singletons are evil because they make you feel that you are writing object- 


oriented code, but in reality they are disguided global variables. Now you can 
ask yourself why this would be a problem. 


71 


12.3 


Sa 


Use Patterns 


This is a problem when you want to modularize your code. In essence, you 
cannot subtitute a singleton with another object, and any change to the sin- 
gleton is widely visible. 


A symptom of the problem is when you want to write tests. You often do not 
want to have your tests impact the complete system. So think twice before 
using a singleton. 


A good way to know if you need a singleton is whether you can add an instance 
variable to your domain objects and pass a reference to the object that you 
would like to have as a singleton. If you can avoid the singleton just with the 
addition of an instance variable, it means that you did not need the singleton. 


This is why good object-oriented designers say that Singleton is about time 
and not space, meaning that you need a singleton when you cannot have two 
instances working at the same time - Think about a scheduler. You cannot 
have two scheduler manipulating threads at the same time. 


The following guideline is an example of a Singleton bad use. 


Guideline: Avoid explicit Transcript 


We present why Transcript can be really badly used. We present that with 
some simple care we can develop modular solutions that are flexible and can 
take advantages of using Transcript without the inconvenients. Let us imag- 
ine that you still want to log strings. 


First simple case 


Transcript is a kind of stdout on which you can write some strings outputs. It 
is cheap. The class exposes a stream-based API (and this is a really important 
design point as we will see in the future). 


Here is a typical not really good use of Transcript 


myMethod 
Transcript show: 'foo' ; cr 


It is not really good because it hardcodes a reference to Transcript while 
Pharo proposes some helpers methods such as traceCr:. 


myMethod 
self traceCr: 'foo 


Some developers may think that this is not important but it can help you if one 
day you want to control the logging and for example use an object with the 
same API but to do something else. So avoid hardcoding globals. But there is 
more. 
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12.4 


12.4 The real concern 


The real concern 


The problem amongst others is that Transcript is a singleton and in fact a 
global variable. Once you use it for real in your code, you basically killed the 
modularity of your program and the only thing that you can do is to hope that 
nothing bad can happen. 


Let us look at a concrete simple case. The microdown Parser came (yes we re- 
moved this) with a simple method named closeMe: 


MicAbstractBlock >> closeMe 
Transcript << ‘Closing ' << self class name; cr; endEntry 


So this method is producing a little trace so that the parser developer could 
understand what was happening. So you can think that this is ok. 


There are two main problems: 


e First what if you want to deploy your application in a system where you 
do not want at all to get Transcript its class and all its family. Think for 
example about people producing minimal images. 


* Second, when Pharo is built on Jenkins all the tests are executed because 
we love tests. And this Transcript expression produces dirt on the build 
log. You do not want to have read such a trace when you are trying to 
understand why the build is not working. 


| Closing MicCodeBlock 


Closing MicCodeBlock 
Closing MicCodeBlock 
Closing MicCodeBlock 
Closing MicCodeBlock 
Closing MicCodeBlock 
Closing MicCodeBlock 
Closing MicCodeBlock 
Closing MicHeaderBlock 
Closing MicHeaderBlock 
Closing MicHeaderBlock 
Closing MicHeaderBlock 
Closing MicListItemBlock 
Closing MicListItemBlock 


Closing MicOrderedListBlock 


Now let us see the good way to have a log and be able to unplug it. 
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12.6 


Use Patterns 


Guideline: Parametrized your object with log stream 


The solution is really simple. Just use object-oriented programming and en- 
capsulation. To support the Parser developer, we can simply add a stream to 
the class. 


For example we define a new variable to and initialize it to a write stream. 


| Object subclass: #MicAbstractBlock 


instanceVariableNames: 'parent children parser logStream' 
classVariableNames: '' 
package: 'Microdown-Model' 


| MicAbstractBlock >> initialize 


super initialize. 
children := OrderedCollection new. 
logStream := WriteStream on: (String new: 1000) 


Then we can rewrite the method closeMe as follows 


| MicAbstractBlock >> closeMe 


logStream << ‘Closing ' << self class name; cr 


Then we can provide a simple setter method so that the developer can set for 
example the Transcript as a stream to write to. 


MicAbstractBlock >> logStream: aStream 
logStream := aStream 


When instance creation is delicate 


If we do not control the creation of instances of the class using the stream, 
we will have difficulties configuring it with the correct stream. So if you want 
to be able to configure the class to use a different logger, we should define a 
class variable so that we can send message to the class and at initialization 
time, we can take the value from the class variable instead of hardcoding the 
WriteStream. 


Here is a sketch to illustrate the idea. 


We add a class variable DefaultStream to the class. 


Object subclass: #MicAbstractBlock 
instanceVariableNames: ‘parent children parser logStream' 
classVariableNames: 'DefaultStream' 
package: 'Microdown-Model' 
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12.6 When instance creation is delicate 


We define one setter. This is using this setter that we will be able to say to the 
system that for a given execution it should write to the Transcript: for exam- 
ple doing MicAbstractBlock logStream: Transcript. 


MicAbstractBlock class >> logStream: aStream 
DefaultStream := aStream 


We make sure that the class variable is initialized to a default stream. Now we 
do it in way that we can later reset the stream to such default stream. 


MicAbstractBlock class >> reset 
self logStream: (WriteStream on: (String new: 1000) ) 


Here we hardcode the stream and alternate solution that extract this expres- 
sion in a separate messages if it makes sense for subclass to specialize. 


MicAbstractBlock class >> initialize 
self reset 


And we will be able to reset the default solution either by reinitializing the 
class MicAbstractBlock initialize or MicAbstractBlock logStream: 
MicAbstractBlock defaultValueForStream 


Now we make sure that the instance creation uses the default stream hold by 
the class. 
MicAbstractBlock >> initialize 

super initialize. 

children := OrderedCollection new. 

logStream := DefaultStream 


The net result is that we have control and can decide what is happening. In 
addition, we can write tests to make sure that the logging is correct. Because 
using Transcript makes this a brittle exercise since someone else may write to 
the Transcript when you do not expect it. 


Conclusion 


Transcript is not bad per se. But it promotes bad coding practices. Develop- 
ers should stop listening to the sirens of easy and cheap global variables. With 
a little bit of care and a limited infrastructure, it is possible to get the best of 
both worlds: modular objects and taking advantage of the existing infrastruc- 
ture whose Transcript belongs to. 


What we presented about Transcript can be applied to any global object or 
singleton. This is not because a library exposes a singleton that you have to 
blindly use. You should apply sound principles and protect yourself from the 
impact of changes. 
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12.7 Guideline: Wrap explicit signal raising 


One question that you can ask yourself is which one of the two following situa- 
tion is the best: 


e Case one. Using the expression self error: ‘Oh no!" and defining 
the method error: in your class (or calling) 


e Case two. Using the expression Error signal: 'Oh no!' 


The case one is better. As general principle, defining a method and sending a 
message is often better because sending self-send messages create hooks that 
your subclasses can take advantage of. 


For example imagine the following situation 


[ MyClass >> ohNoError 
Error signal: 'Oh no!' 


| MyClass >> ohNoErrorUser 
x isSomethingBad 
ifTrue: [ self error: ‘Oh no!' ] 


Then you can redefine ohNoError in your subclass. 


| MyClassSubclass >> ohNoError 
Error signal: 'Oh no! Really no!' 
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CHAPTER 3 


Conclusion 


We hope that you enjoyed this guideline list. Remember that you write code 
once and will read it a thousand times. Take the time to give good names. 
However, finding good names is not an easy task, but you can use refactorings 
to improve things easily. 


This goes in pairs with tests. 


You write a test once and it gets executed a million times. Therefore, write 
tests to exercise the names you use and change them until they help you tell 
stories that can be understood. 
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